Couchbase
Summary
This document covers the information to gather from Couchbase in order to configure a Qarbine data service. The data service will use the Qarbine Couchbase driver. You can define multiple data services that access the same Couchbase endpoint though with varying credentials. Once a data service is defined, you can manage which Qarbine principals have access to it and its associated Couchbase data. A Qarbine administrator has visibility to all data services.
Overview
Couchbase is a NoSQL database which provides an SQL-like querying interaction. For details, see the Couchbase home page at https://couchbase.com.
Enabling Qarbine access to your cluster data involves the following steps:
- Determining the Couchbase URL and bucket,
- Adding or identifying a Couchbase user account and its password,
- Enabled IP access and
- Defining a Qarbine Data Service.
Couchbase Information
Endpoint
Navigate to your Couchbase console. For Couchbase Capella it is at
https://cloud.couchbase.com/
Information on adding users can be found at
https://docs.couchbase.com/server/current/manage/manage-security/manage-users-and-roles.html
To locate your Couchbase URL navigate to the databases page by clicking
Click on the cluster of interest.
Click
Copy the public connection string
This value is used as the “server template” in the Qarbine data service.
Another DNS name of interest is the hostname shown below.
Database Account
You should have identified a user account and its password for Qarbine readonly interactions. For reference shown below would be an example of creating a user with just these permissions. You may wish to limit bucket access as well based on your requirements.
For more details see https://docs.couchbase.com/cloud/clusters/manage-database-users.html.
Buckets and Scopes
Conceptually,
- Buckets map to SQL databases,
- Scopes map to SQL schemas, and
- Collections map to SQL tables.
To see your buckets navigate to the Couchbase cluster tab shown below.
Below is a listing with some of the examples loaded.
Expand each of these shows he following
Identify the scope of interest for each bucket. Usually there is just one, well-named scope that is the one to use for Qarbine querying. The Qarbine database value described below is formatted with the bucket name, a space, and the scope name.
Bucket | Scope of Interest | Qarbine “Database” value |
---|---|---|
beer-sample | _default | beer-sample _default |
rgbBucket | rgbScope | rgbBucket rgbScope |
travel-bucket | inventory | travel-bucket inventory |
When the Qarbine data service’s database field is empty, you will have to fully qualify the collection path in your queries.
Allowing an IP address
Add the Qarbine host IP address to the cluster’s list of allowed IPs using the information at
Optional Data Preparation
A quick way to start working with data in your cluster is to load one or more sample buckets. Sample buckets contain example data, as well as example indexes, for your experimentation. The Qarbine Couchbase example components and tutorial use these sample data sets.
Find and import sample buckets under the cluster’s [Tools > Import tab]. The Couchbase documentation has further information about working with sample data at
Navigate to
and then to the tab
Chose the following sample data sets
and
You want them each to show
Qarbine Data Service Configuration
Overview
The Qarbine data service requires
- Qarbine compute node URL,
- Couchbase URL,
- Couchbase user and password, and
- Couchbase default bucket.
Compute Node Preparation
Determine which compute node service endpoint you want to run this data access from. That URL will go into the Data Service’s Compute URL field. Its form is “https://domain:port/dispatch”. A sample is shown below.
The port number corresponds to a named service endpoint configured on the given target host. For example, the primary compute node usually is set to have a ‘main’ service. That service’s configuration is defined in the ˜./qarbine.service/config/service.main.json file. Inside that file the following driver entry is required
"drivers" :[
. . .
"./driver/couchbaseDriver.js"
]
The relevant configuration file name for non primary (main) Qarbine compute nodes is service.NAME.json. Remember to have well formed JSON syntax or a startup error is likely to occur. If you end up adding that entry then restart the service via the general command line syntax
pm2 restart <service>
For example,
pm2 restart main
or simply
pm2 restart all
Defining the Qarbine Data Service
Within the Qarbine Administration tool navigate to Data Services
Click
Enter the name, description, and Qarbine compute node endpoint URL.
Choose
For the server template enter
couchbases://THE_COPIED_URL_FROM_ABOVE
For the server options enter
userName="THE_USER",
password="THE_PASSWORD",
configProfile = "wanDevelopment"
Optionally you may specify the following options:
- consoleLogLevel
- ssl (the default is “no_verify”)
- tls_verify=none
- kvTimeout
- kvDurableTimeout
- viewTimeout
- queryTimeout
- analyticsTimeout
- searchTimeout
- managementTimeout
You can reference environment variables using the syntax %NAME%. Any strings should be quoted and the key\value pairs separated by commas. For further information see
https://docs.couchbase.com/go-sdk/current/howtos/troubleshooting-cloud-connections.html
https://docs.couchbase.com/nodejs-sdk/current/ref/client-settings.html
The “database” field here maps to a Couchbase bucket and scope name with a space separator as described above.
After you have entered the above information save the data service by clicking .
Next, test the settings by clicking on the icon noted below.
You should see the following general dialog
The data service will be known at the next log on time.
Data Service Query Interactions
For retrieving data from Couchbase Qarbine supports using a JSON specification. The format is
{
useSearch: true | false,
bucket: aString,
scope: aString,
index: aString, ← required.
other fields per Couchbase documentation
}
The useSearch flag determines whether the search or query endpoint is used. The configured Qarbine Data Service’s server template prefix (couchbase:// vs couchbases://) determines whether the HTTPS secure endpoint is used. The cbHostName value is the text after couchbase(s):// in the server template. A sample secure server template is
couchbases://cb.abcdefghijk.cloud.couchbase.com
Its cbHostName is
cb.abcdefghijk.cloud.couchbase.com
Protocol | Type | Endpoint |
---|---|---|
HTTP | query | http://${cbHostName}:8093 |
search | http://${cbHostName}:8094 | |
HTTPS | query | https://${cbHostName}:18093 |
search | https://${cbHostName}:18094 |